<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
          "http://www.w3.org/TR/html4/loose.dtd">

<html lang="en">

<head>
  <meta http-equiv="Content-Type"
        content="text/html; charset=utf-8">
  <meta http-equiv="Content-Style-Type"
        content="text/css">
  <meta http-equiv="Content-Script-Type"
        content="text/javascript">
  <meta name="description"
        content="FreeType Documentation">
  <meta name="Author"
        content="David Turner">

  <link rel="icon"
        href="../image/favicon_-90.ico">
  <link rel="shortcut icon"
        href="../image/favicon_-90.ico">
  <link rel="stylesheet"
        type="text/css"
        href="../css/freetype2_-90.css">

  <script type="text/javascript"
          src="../../../js/jquery-1.11.0.min.js">
  </script>
  <script type="text/javascript"
          src="../../../js/jquery.ba-resize.min.js">
  </script>
  <script type="text/javascript"
          src="../../../js/freetype2.js">
  </script>

  <title>FreeType Glyph Conventions / V</title>
</head>


<body>

<div id="top"
     class="bar">
  <h1><a href="http://freetype.org/index.html">FreeType</a> Glyph
    Conventions&nbsp;/&nbsp;V</h1>
</div>


<div id="wrapper">

<div class="colmask leftmenu">
  <div class="colright">
    <div class="col1wrap">
      <div class="col1">


        <!-- ************************************************** -->

        <div id="text-processing">
          <h2>V. Text Processing</h2>

          <p>This section demonstrate algorithms which use the
            concepts previously defined to render text, whatever
            layout you use.  It assumes <em>simple</em> text handling
            suitable for scripts like Latin or Cyrillic, using a
            one-to-one relationship between input character codes and
            output glyphs indices.  Scripts like Arabic or Khmer,
            which need a &lsquo;shaping engine&rsquo; to do the
            character code to glyph index conversion, are beyond the
            scope (and should be done by proper layout engines
            like <a href="http://www.pango.org/">Pango</a>
            anyway).</p>


          <h3 id="section-1">1. Writing simple text strings</h3>

          <p>In this first example, we will generate a simple string
            of text in the Latin script, i.e., with a horizontal
            left-to-right layout.  Using exclusively pixel metrics,
            the process looks like:

            <ol class="algorithm">
              <li>
                Convert the character string into a series of glyph
                indices.
              </li>
              <li>
                Place the pen to the cursor position.
              </li>
              <li>
                Get or load the glyph image.
              </li>
              <li>
                Translate the glyph so that its &lsquo;origin&rsquo;
                matches the pen position.
              </li>
              <li>
                Render the glyph to the target device.
              </li>
              <li>
                Increment the pen position by the glyph's advance
                width (in pixels).
              </li>
              <li>
                Start over at step&nbsp;3 for each of the remaining
                glyphs.
              </li>
              <li>
                When all glyphs are done, set the text cursor to the
                new pen position.
              </li>
            </ol>

          <p>Note that kerning isn't part of this algorithm.</p>


          <h3 id="section-2">2. Subpixel positioning</h3>

          <p>This algorithm can be used for hinting modes that don't
            apply horizontal hinting.  It essentially provides WYSIWYG
            text layout.  Text rendering is very similar to the
            algorithm described in subsection&nbsp;1, with the
            following few differences:</p>

          <ul>
            <li>
              <p>The pen position is expressed in fractional
                pixels.</p>
            </li>
            <li>
              <p>The hinted outline must be shifted horizontally to
                the proper sub-pixel position.</p>
            </li>
            <li>
              <p>The advance width is expressed in fractional pixels,
                and isn't necessarily an integer.</p>
            </li>
          </ul>

          <p>Here an improved version of the algorithm:</p>

          <ol class="algorithm">
            <li>
              Convert the character string into a series of glyph
              indices.
            </li>
            <li>
              Place the pen to the cursor position.  This can be a
              non-integer point.
            </li>
            <li>
              Get or load the glyph image.
            </li>
            <li>
              Translate the glyph by &lsquo;pen_pos -
              floor(pen_pos)&rsquo;.
            </li>
            <li>
              Render the glyph to the target device at
              &lsquo;floor(pen_pos)&rsquo;.
            </li>
            <li>
              Increment the pen position by the glyph's advance width
              in fractional pixels.
            </li>
            <li>
              Start over at step&nbsp;3 for each of the remaining
              glyphs.
            </li>
            <li>
              When all glyphs are done, set the text cursor to the new
              pen position.
            </li>
          </ol>


          <h3 id="section-3">3. Simple kerning</h3>

          <p>Adding kerning to the basic text rendering algorithm is
            easy: When a kerning pair is found, simply add the scaled
            kerning distance to the pen position before step&nbsp;4.
            Of course, the distance should be rounded in the case of
            algorithm&nbsp;1, though it doesn't need to for
            algorithm&nbsp;2.  This gives us:</p>

          <p>Algorithm&nbsp;1 with kerning:</p>

          <ol class="algorithm">
            <li>
              Convert the character string into a series of glyph
              indices.
            </li>
            <li>
              Place the pen to the cursor position.
            </li>
            <li>
              Get or load the glyph image.
            </li>
            <li>
              Add the rounded scaled kerning distance, if any, to the
              pen position.
            </li>
            <li>
              Translate the glyph so that its &lsquo;origin&rsquo;
              matches the pen position.
            </li>
            <li>
              Render the glyph to the target device.
            </li>
            <li>
              Increment the pen position by the glyph's advance width
              in pixels.
            </li>
            <li>
              Start over at step&nbsp;3 for each of the remaining
              glyphs.
            </li>
          </ol>

          <p>Algorithm&nbsp;2 with kerning:</p>

          <ol class="algorithm">
            <li>
              Convert the character string into a series of glyph
              indices.
            </li>
            <li>
              Place the pen to the cursor position.
            </li>
            <li>
              Get or load the glyph image.
            </li>
            <li>
              Add the scaled unrounded kerning distance, if any, to
              the pen position.
            </li>
            <li>
              Translate the glyph by &lsquo;pen_pos -
              int(pen_pos)&rsquo;.
            </li>
            <li>
              Render the glyph to the target device at
              &lsquo;int(pen_pos)&rsquo;.
            </li>
            <li>
              Increment the pen position by the glyph's advance width
              in fractional pixels.
            </li>
            <li>
              Start over at step&nbsp;3 for each of the remaining
              glyphs.
            </li>
          </ol>


          <h3 id="section-4">4. Right-to-left layout</h3>

          <p>The process of laying out right-to-left scripts like
            (modern) Hebrew text is very similar.  The only difference
            is that the pen position must be decremented before the
            glyph rendering (remember: the advance width is always
            positive, even for Hebrew glyphs).</p>

          <p>Right-to-left algorithm&nbsp;1:</p>

          <ol class="algorithm">
            <li>
              Convert the character string into a series of glyph
              indices.
            </li>
            <li>
              Place the pen to the cursor position.
            </li>
            <li>
              Get or load the glyph image.
            </li>
            <li>
              Decrement the pen position by the glyph's advance
              width in pixels.
            </li>
            <li>
              Translate the glyph so that its &lsquo;origin&rsquo;
              matches the pen position.
            </li>
            <li>
              Render the glyph to the target device.
            </li>
            <li>
              Start over at step&nbsp;3 for each of the remaining
              glyphs.
            </li>
          </ol>

          <p>The changes to algorithm&nbsp;2, as well as the inclusion
            of kerning are left as an exercise to the reader.</p>


          <h3 id="section-5">5. Vertical layouts</h3>

          <p>Laying out vertical text uses exactly the same processes,
            with the following significant differences:</p>

          <ul>
            <li>
              <p>The baseline is vertical, and the vertical metrics
                must be used instead of the horizontal one.</p>
            </li>
            <li>
              <p>The left bearing is usually negative, but this
                doesn't change the fact that the glyph origin must be
                located on the baseline.</p>
            </li>
            <li>
              <p>The advance height is always positive, so the pen
                position must be decremented if one wants to write top
                to bottom (assuming the <i>Y</i>&nbsp;axis is oriented
                upwards).</p>
            </li>
          </ul>

          <p>Here the algorithm:</p>

          <ol class="algorithm">
            <li>
              Convert the character string into a series of glyph
              indices.
            </li>
            <li>
              Place the pen to the cursor position.
            </li>
            <li>
              Get or load the glyph image.
            </li>
            <li>
              Translate the glyph so that its &lsquo;origin&rsquo;
              matches the pen position.
            </li>
            <li>
              Render the glyph to the target device.
            </li>
            <li>
              Decrement the vertical pen position by the glyph's
              advance height in pixels.
            </li>
            <li>
              Start over at step&nbsp;3 for each of the remaining
              glyphs.
            </li>
            <li>
              When all glyphs are done, set the text cursor to the new
              pen position.
            </li>
          </ol>
        </div>

        <!-- ************************************************** -->

        <div class="updated">
          <p>Last update: 13-Feb-2018</p>
        </div>
      </div>
    </div>


    <!-- ************************************************** -->

    <div class="col2">
    </div>
  </div>
</div>


<!-- ************************************************** -->

<div id="TOC">
  <ul>
    <li class="funding">
      <form action="https://www.paypal.com/cgi-bin/webscr"
            method="post"
            target="_top">
        <input type="hidden"
               name="cmd"
               value="_s-xclick">
        <input type="hidden"
               name="hosted_button_id"
               value="SK827YKEALMT4">
        <input type="image"
               src="https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif"
               name="submit"
               alt="PayPal - The safer, easier way to pay online!">
        <img alt=""
             border="0"
             src="https://www.paypalobjects.com/de_DE/i/scr/pixel.gif"
             width="1"
             height="1">
      </form>
    </li>
    <li class="primary">
      <a href="http://freetype.org/index.html">Home</a>
    </li>
    <li class="primary">
      <a href="http://freetype.org/index.html#news">News</a>
    </li>
    <li class="primary">
      <a href="../index.html">Overview</a>
    </li>
    <li class="primary">
      <a href="../documentation.html">Documentation</a>
    </li>
    <li class="primary">
      <a href="http://freetype.org/developer.html">Development</a>
    </li>
    <li class="primary">
      <a href="http://freetype.org/contact.html"
         class="emphasis">Contact</a>
    </li>

    <li>
      &nbsp; <!-- separate primary from secondary entries -->
    </li>

    <li class="secondary">
      <a href="index.html">FreeType Glyph Conventions</a>
    </li>
    <li class="tertiary">
      <a href="glyphs-1.html">Basic Typographic Concepts</a>
    </li>
    <li class="tertiary">
      <a href="glyphs-2.html">Glyph Outlines</a>
    </li>
    <li class="tertiary">
      <a href="glyphs-3.html">Glyph Metrics</a>
    </li>
    <li class="tertiary">
      <a href="glyphs-4.html">Kerning</a>
    </li>
    <li class="tertiary">
      <a href="glyphs-5.html" class="current">Text Processing</a>
    </li>
    <li class="tertiary">
      <a href="glyphs-6.html">FreeType Outlines</a>
    </li>
    <li class="tertiary">
      <a href="glyphs-7.html">FreeType Bitmaps</a>
    </li>
  </ul>
</div>

</div> <!-- id="wrapper" -->

<div id="TOC-bottom">
</div>

</body>
</html>
